Configuring Movie Data Export Components0

Your component may provide one or more configuration functions. These functions allow applications to configure your component before the Movie Toolbox calls your component to start the export process. Note that applications may call these functions directly.

All of these functions are optional. If your component receives a request that it does not support, you should return the badComponentSelector error code. In addition, your component should work properly even if none of these functions is called.

These functions address a variety of configuration issues. Applications can retrieve additional data from your component by calling the MovieExportGetAuxiliaryData function.

Applications can specify a progress function for use by your component by calling the MovieExportSetProgressProc function.

Applications can instruct your component to display its user dialog box by calling the MovieExportDoUserDialog function.

MovieExportSetProgressProc

The MovieExportSetProgressProc function allows an application to assign a movie progress function.



 
pascal ComponentResult MovieExportSetProgressProc

                                          (MovieExportComponent ci, 

                                         MovieProgressUPP proc, 

                                         long refcon);

ci: Identifies the application's connection to your movie data export component.
proc: Contains a pointer to the application's movie progress function. See the chapter "Movie Toolbox" in Inside Macintosh: QuickTime for a complete description of the interface supported by movie progress functions. If this parameter is set to nil , the application is removing its progress function. In this case, your component should stop calling the progress function.
refcon: Specifies a reference constant. Your component should pass this constant back to the application's progress function whenever you call that function.

DESCRIPTION

Some data export operations may be time-consuming, and application developers may therefore choose to display progress information to the user. Your component provides this information to an application's progress function. As your component processes an export request, you should call the progress function occasionally in order to report on the progress of the operation. Use a progress code of progressOpExportMovie . The application can then present this information to the user.

These progress functions must support the same interface as Movie Toolbox progress functions. That interface is discussed in the chapter "Movie Toolbox" in Inside Macintosh: QuickTime . Note that this interface not only allows you to report progress to the application, but also allows the application to cancel the request.

RESULT CODE

badComponentSelector

0x80008002

Function not supported

MovieExportGetAuxiliaryData

The MovieExportGetAuxiliaryData function allows an application to retrieve additional data from your component. This additional data may be created during the data export process.



 
pascal ComponentResult MovieExportGetAuxiliaryData

                                          (MovieExportComponent ci,

                                         Handle dataH, 

                                         OSType *handleType);

ci: Identifies the application's connection to your movie data export component.
data: Contains a handle that is to be filled with the additional data. Your component should resize this handle as appropriate. Your component is not responsible for disposing of this handle.
handleType: Contains a pointer to the type of data you place in the handle specified by the data parameter.

DESCRIPTION

The MovieExportGetAuxiliaryData function allows an application to retrieve additional data that is generated during the data export process. The application may then use the data as appropriate. Your component may create this data in cases where the target data type cannot accommodate all of the converted data. For example, if your component exports data into 'TEXT' handles or files, you might choose to preserve associated style information for that text. However, 'TEXT' resources cannot store that style information. You could save that style information in a 'styl' handle and allow an application to retrieve it after the conversion.

Your component should expect the application to call this function after the export process ends.

RESULT CODE

badComponentSelector

0x80008002

Function not supported

MovieExportDoUserDialog

The MovieExportDoUserDialog function allows an application to request that your component display its user dialog box. This provides an opportunity for the user to configure your export component.



 
pascal ComponentResult MovieExportDoUserDialog 

                                         (MovieExportComponent ci, 

                                          Movie theMovie,

                                          Track onlyThisTrack,

                                          TimeValue startTime,

                                          TimeValue duration,

                                          Boolean *canceled);

ci: Identifies the application's connection to your movie data export component.
theMovie: Identifies the movie containing the data to be exported.
onlyThisTrack: Specifies that the export component should only attempt to export the data from a single track. If this parameter is set to nil , the exporter should attempt to export the entire movie, or all of the tracks in the movie that it can export. For example, an audio export component might export multiple audio tracks, mixing them if necessary. If this parameter is not nil , the exporter should attempt to export only the specified track.
startTime: Specifies the movie time at which to begin the export operation. If you pass 0, the operation should start at the beginning of the movie or track.
duration: Specifies the duration, in movie timescale units, of the segment to be exported. To export the entire movie, or an entire track, pass in the value returned by GetMovieDuration or GetTrackDuration , minus the value passed in startTime , as described above.
canceled: Contains a pointer to a Boolean value. Your component should set this value to true if the user cancels the dialog box, otherwise false . If the user cancels the dialog box, your component should revert to its settings prior to executing the MovieExportDoUserDialog function

DESCRIPTION

Your movie data export component may support a user dialog box that allows the user to configure an export operation. For components that support such a dialog box, the MovieExportDoUserDialog function lets an application tell you when to display the dialog box to the user. If your component supports a user dialog box, be sure to set the hasMovieExportUserInterface flag in your component's componentFlags field.

RESULT CODE

badComponentSelector

0x80008002

Function not supported